Skip to main content

动态下拉菜单

有时，API 端点要求客户端指定一个父对象，以创建或访问子资源。例如，指定一个电子表格 ID 来检索其工作表。由于人们通常不会使用自动递增的 ID，因此 Zapier 需要提供一种简单的方式，让用户使用易读的人类友好标识选择该父对象。

我们的解决方案是为用户呈现一个下拉菜单，该菜单通过向 API 发起实时调用来获取父对象列表。我们将这些特殊的下拉菜单称为“动态下拉菜单”。

定义​

要定义一个动态下拉菜单，您需要在 inputFields 对象中添加 dynamic 属性。该属性的值是一个用点号分隔的字符串。

//...issue: {key:'issue',//...create: {//...operation: {inputFields: [{key:'project_id',required:true,label:'This is a dynamic dropdown',dynamic:'project.id.name'},// will call the trigger with a key of project{key:'title',required:true,label:'Title',helpText:'What is the name of the issue?'}]}}}

这个点号分隔的字符串遵循以下模式：

  • 用于驱动下拉菜单的触发器的键。必填
  • 将在 bundle.inputData 中提供的值。必填
  • 显示在下拉菜单左侧的粗体人类友好值。可选

在上述代码示例中，dynamic 属性引用了一个键为 project 的触发器。假设该触发器返回一个对象数组，且每个对象包含 id 和 name 键，例如：

[{id:"1",name:"First Option",dateCreated:"01/01/2000"},{id:"2",name:"Second Option",dateCreated:"01/01/2000"},{id:"3",name:"Third Option",dateCreated:"01/01/2000"},{id:"4",name:"Fourth Option",dateCreated:"01/01/2000"},];

动态下拉菜单的显示效果如下。

Platform UI vs CLI comparison

使用资源​

在第一个代码示例中，动态下拉菜单是由触发器驱动的。您也可以使用资源来驱动动态下拉菜单。为此，请将资源键和资源方法结合使用驼峰命名法。

constApp={// ...resources:{project:{key:"project",// ...list:{// ...operation:{perform:()=>{return[{id:123,name:"Project 1"}];},// called for project_id dropdown},},},issue:{key:"issue",// ...create:{// ...operation:{inputFields:[{key:"project_id",required:true,label:"Project",dynamic:"projectList.id.name",},// calls project.list{key:"title",required:true,label:"Title",helpText:"What is the name of the issue?",},],},},},};

隐藏触发器​

在某些情况下，您需要为动态下拉菜单提供数据，但不希望让触发器对最终用户可见。此时，最佳实践是创建触发器并在其 display 对象中设置 hidden: true。

constApp={// ...triggers:{new_project:{key:"project",noun:"Project",// `display` controls the presentation in the Zapier Editordisplay:{label:"New Project",description:"Triggers when a new project is added.",hidden:true,},operation:{perform:projectListRequest,},},another_trigger:{// Another trigger definition...},},};

下拉菜单之间的依赖关系​

您可以在一个触发器或操作中包含多个动态下拉菜单。在某些情况下，一个动态下拉菜单的 API 调用依赖于另一个动态下拉菜单的选择值。Google Sheets 集成展示了这种模式的示例。

下面的示例说明了一个“新工作表”触发器，该触发器填充一个动态下拉菜单输入字段来选择工作表：

{key:"worksheet",// ...operation: {// ...perform:async(z,bundle)=>{constresponse=awaitz.request("https://example.com/api/v2/projects.json", {params:{spreadsheet_id:bundle.inputData.spreadsheet_id,},});// response.throwForStatus() if you're using core v9 or olderreturnresponse.data;// or response.json if you're using core v9 or older}}}

假设有一个“新记录”触发器，其中包含“电子表格”和“工作表”动态下拉菜单输入字段，分别使用键 spreadsheet_id 和 worksheet_id。所选电子表格的值可以通过 bundle.inputData.spreadsheet_id 用于工作表触发器。

constApp={// ...triggers:{// ...issue:{key:"new_records",// ...operation:{inputFields:[{key:"spreadsheet_id",required:true,label:"Spreadsheet",dynamic:"spreadsheet.id.name",altersDynamicFields:true,},{key:"worksheet_id",required:true,label:"Worksheet",dynamic:"worksheet.id.name",},],},},},};

注意：请注意，一个动态下拉菜单可以依赖于另一个动态下拉菜单的选择值。字段之间可能存在两种类型的依赖关系：
要求依赖：影响依赖字段在 UI 中的启用或禁用状态。
设置 required: false 会使字段变为可选并始终启用。
未设置 required 值会使字段变为可选，并在依赖项被选择前禁用。
值依赖：影响动态下拉菜单字段选项的检索方式。
设置或不设置 required 值不会影响动态字段选项的检索。
因此，如果您有一个可选的动态下拉菜单依赖于另一个下拉菜单输入字段，则不应在其上设置 required: false。输入字段默认是可选的，但在依赖于另一个字段的可选动态下拉菜单上设置 required: false 会移除要求依赖关系。
在上述示例中，worksheet_id 输入字段会在 spreadsheet_id 输入字段有值前被禁用（如在 Zapier 的产品中，例如 Zap 编辑器）。请注意，设置 altersDynamicFields: true 表示当该字段的值更改时，其他输入字段需要重新计算。

检测触发器是否用于动态下拉菜单​

如果您希望您的触发器为动态下拉菜单执行特定脚本，则需要使用 bundle.meta.isFillingDynamicDropdown。这在需要为动态下拉菜单使用分页 来加载更多选项时非常有用。

constApp={// ...resources:{project:{key:"project",// ...list:{// ...operation:{canPaginate:true,perform:()=>{if(bundle.meta.isFillingDynamicDropdown) {// perform pagination request here}else{return[{id:123,name:"Project 1"}];}},},},},issue:{key:"issue",// ...create:{// ...operation:{inputFields:[{key:"project_id",required:true,label:"Project",dynamic:"projectList.id.name",},// calls project.list{key:"title",required:true,label:"Title",helpText:"What is the name of the issue?",},],},},},},};

链接搜索操作​

此功能可以让用户更轻松地处理工作流中多步骤的以下场景：

  • 输入字段的值依赖于早期步骤的输出字段。
  • 该输出字段的值无法直接使用。
  • 用户需要添加一个额外的搜索步骤，将无法直接使用的输出转换为可用的内容。

示例：假设输入字段需要潜在客户的 ID。用户可以从动态下拉菜单中选择潜在客户，但这样工作流每次运行时都会作用于同一个潜在客户。早期步骤返回了潜在客户的电子邮件地址，但不是他们的 ID。用户需要先添加一个搜索步骤，使用电子邮件地址来返回 ID。

用户可以自己完成此操作，但通过使用此功能，Zapier 的产品可以使此任务更简单。

如何为用户工作​

例如，在 Zap 编辑器中，使用此功能的动态下拉菜单会在下拉菜单旁边显示一个按钮。用户点击按钮后，正确的搜索步骤会自动添加到工作流开头，并将正确的输出字段映射到动态下拉菜单。

Platform UI vs CLI comparison

如何配置它​

在输入字段的定义中，配置 search 属性，其值为 <search_key>.<output_key>。

  • 用应该添加到用户工作流的搜索操作的 key 替换 <search_key>。
  • 用该搜索操作的输出字段的 key 替换 <output_key>，该字段将作为输入字段的值映射。

以下是示例：

{key:'project_id',required:true,label:'Project',dynamic:'list_projects.id.name',search:'search_projects.id',}